前言：README 寫得爛，去看程式碼不就好了？

「README 寫得爛，去看程式碼註解或原始碼不就好了？」

這句話沒錯，但代價是：新使用者要多花一段時間，自己爬程式碼才能知道這個套件能做什麼。今天實際核對一次 omnipay-ecpay 的文件現況，看這個代價具體有多大。

今日目標

• 核對這個套件目前的 README、CHANGELOG 各自停在什麼狀態
• 對照套件實際的功能範圍（前兩天看過的 Trait、SDK 包裝），量化「文件缺了多少」
• 理解「文件沒跟上」跟「文件是假的」是兩回事,但對使用者造成的困擾很類似
• 想清楚：測試案例能補上多少文件的缺口,補不上的又是什麼

兩份文件,兩種停滯

README.md（72 行）開頭就寫著：

**Skeleton gateway for the Omnipay PHP payment processing library**

This is where your description should go. Try and limit it to a paragraph or two, and maybe throw in a
mention of what PSRs you support to avoid any confusion with users and contributors.

這段文字一字不改地留著 Omnipay 官方骨架套件產生器（omnipay-skeleton）給的範本提示語——它原本的意思是「這裡應該換成你自己的描述」，但沒有人接手改掉它。往下的 ## Usage 也只有一行：

The following gateways are provided by this package:

* ecpay

CHANGELOG.md 更明顯：

## NEXT - YYYY-MM-DD

### Added
- Nothing

日期還是佔位字串 YYYY-MM-DD，六個分類（Added/Deprecated/Fixed/Removed/Security）底下全部寫著「Nothing」。這個套件已經有 36 個 commit、橫跨 2021 到 2025 年的開發歷史，但 CHANGELOG 裡一行紀錄都沒有。

落差有多大：文件說的 vs 實際做得到的

README 只告訴你「這個套件提供 ecpay 這個 gateway」，沒有告訴你：

• 支援哪些付款方式（前兩天看過的：信用卡、ATM、超商代碼/條碼、無卡分期、彈性分期）
• 每種付款方式各自需要哪些必填參數（HasCreditFields 裡一大堆分期/定期定額欄位）
• 這個套件怎麼處理電子發票（HasInvoiceFields）
• 這個套件底層依賴綠界官方 SDK，版本要求是什麼（ecpay/sdk: ^1.3）

這些資訊,現在只存在於三個地方：程式碼本身、Trait 的中文註解、還有測試案例。對一個第一次接觸這個套件的開發者來說，讀 README 得到的資訊量幾乎是零，要真的知道能做什麼，得自己去讀原始碼。

測試案例能補上多少缺口？

昨天、前天看過的內容已經證明：測試案例確實能回答一部分「這個套件支援什麼」的問題。PurchaseRequestTest.php 裡明確寫著 testGetData、testATMGetData、testBNPLGetData、testFlexibleInstallmentGetData——只要看測試方法名稱,就能猜到支援哪幾種付款方式。

但測試案例補不上的東西也很明確：

• 測試不會告訴你「為什麼」：HasCreditFields 裡每個欄位的中文註解解釋了綠界的業務規則（例如「銀聯卡交易不支援分期付款」），這些規則不會出現在測試斷言裡，只存在於原始碼註解
• 測試不會告訴你完整的參數清單跟預設值：你要嘛自己讀 Trait，要嘛靠 IDE 的自動完成猜
• 測試不會告訴你版本相容性、安裝方式：這些是 README 該做的事，測試從來不負責這塊

❌ vs ✅：文件缺口造成的實際使用者困擾

❌ 使用者只看 README 的心路歷程
1. 讀完 README，只知道 `composer require` 之後有個叫 ecpay 的 gateway
2. 不知道要用信用卡分期，得傳 CreditInstallment 參數
3. Google「omnipay ecpay CreditInstallment」，找不到文件
4. 翻開 src/Traits/HasCreditFields.php，才在原始碼註解裡找到答案

✅ 如果測試案例先被當成文件來讀
1. 讀完 README 大概知道有 ecpay 這個 gateway
2. 打開 tests/Message/PurchaseRequestTest.php，看到 testFlexibleInstallmentGetData
   裡示範了 CreditInstallment = '30N' 怎麼設定
3. 對照 src/Traits/HasCreditFields.php 的中文註解，補齊業務規則細節
4. 兩份資料一起看，比單看任何一份都完整

正例仍然比一份寫好的 README 慢，但至少走得通——前提是使用者知道要去看測試，而且測試案例真的覆蓋到他想用的那個付款方式。這正是為什麼「測試覆蓋不均」不只是品質問題，也是文件問題：一個沒被測到的付款方式，等於使用者連「測試充當文件」這條後路都沒有。這件事我們明天會用具體數字攤開來看。

今日思考題

你維護或用過的套件裡，有沒有「文件停在很早期的版本，程式碼卻一直在動」的情況？你當時是怎麼補上這個落差的——讀原始碼、讀測試，還是直接去問維護者？

今日重點回顧

• README 還留著骨架產生器的範本提示語，CHANGELOG 從未被填寫過一筆紀錄
• 文件缺口目前完全靠原始碼本身、Trait 中文註解、測試案例三者拼湊補上
• 測試案例能回答「支援什麼」，但回答不了「為什麼」跟「完整參數清單」
• 測試覆蓋不均，會讓「測試充當文件」這條後路在沒被測到的地方直接斷掉

明日預告

明天正式進入測試現況的數字盤點：21 個測試方法，到底哪些付款方式測得細、哪些只測了最基本的情境,還有這個套件裡測得最紮實的一段——防止偽造付款通知的簽章驗證測試。